Skip to content

feat: typed capability sources with validation, approval and typed answers - #6

Merged
mukezhz merged 7 commits into
mainfrom
feat/typed-capability-sources
Nov 16, 2026
Merged

mukezhz merged 7 commits into
mainfrom
feat/typed-capability-sources

Conversation

@mukezhz

@mukezhz mukezhz commented Nov 16, 2026 •

Copy link
Copy Markdown
Owner

Problem

Protobuf read as the core of codemode, so every integration meant buf config, a vendored codemode.proto, and then a hand-written switch rpc with request structs duplicating the schema and their own JSON decoding. Nothing validated a program's arguments before the handler ran, approval was all-or-nothing (Options.Plan), and the answer came back as any.

The core never depended on protobuf (capability, codemode, agent, llm, sandbox, program import neither protobuf nor registry/), so the fix is a developer-facing layer, not a rewrite. ADR 0008 records the decision, including why BAML is not the core.

Solution

source, _ := gosource.New(
	gosource.Func("orders.list", "Lists orders", gosource.Public(), shop.List, gosource.ReadOnly()),
	gosource.Func("orders.refund", "Refunds an order", gosource.Roles("support"), shop.Refund, gosource.NeedsApproval()),
)
mode, _ := codemode.FromSource(source, caller)
revenue, _, err := agent.RunAs[Revenue](ctx, mode, model, request, opts)
  • Sources. codemode.Source{Registry, Execute} is what every adapter produces: capability/gosource (typed Go functions), registry (protobuf), capability/mcpsource (MCP tools). codemode.Combine serves several as one, and duplicate names or RPCs are an error. codemode.FromSource narrows to the caller and defaults to keyword search.
  • Input validation for every source. Each call is checked against its input shape before ExecuteFunc runs: unknown fields, kinds, enums, required fields and oneofs. Errors name the path (items[2].id: want integer, got "2") and go back to the repair loop. A rejected call is not recorded, so it never counts as a write.
  • gosource. The schema comes from Go structs following encoding/json, with desc tags and capability.Enum string types. Access is a required argument with no zero value. Nil slices are sent as [], and a panic in a handler becomes an error.
  • Typed answers. agent.RunAs[T] tells the model T's shape, then checks the return value and decodes it into T. A mismatch is repaired like any other failure.
  • Approval. NeedsApproval comes from gosource.NeedsApproval() or the new (codemode.needs_approval) proto option. It holds that write and every later one, and the run returns *agent.Pending. agent.PlanStore, NewMemoryPlans and ApplyPlan apply a plan once, by ID, for its owner. Outside agent.Run, such a write fails instead of running. mcpserver reports held writes instead of claiming success.
  • Supporting changes. TypeSchema.Required and an integer kind. capability/jsonschema is extracted from mcpsource. codemode/sourcetest.Run is a contract test that every source runs.
  • Example and docs. The todo example defaults to Go functions and keeps -source proto. Docs add a Go-structs quickstart plus pages on sources, types and validation, and approving writes. The protobuf quickstart moves to protobuf.md.

Examples

  • examples/taskreport now serves its 23 capabilities from typed Go functions by default, and -source proto keeps the protos. Both paths run on the same typed methods, and a test checks the two declare the same names, descriptions, roles, reads and approvals. tasks.delete needs approval: the chat shows the held writes with Approve and Reject, backed by POST /api/plans/{id}/approve and /reject. A delete from the task board counts as its own approval and runs at once.
  • examples/shop is the quickstart as a runnable, tested example: Go-struct capabilities, a typed answer with RunAs[Revenue], and a refund approved at the terminal (make demo-shop).
  • examples/combined runs one program over a Go function, the todo proto service and an in-process MCP server through codemode.Combine (make demo-combined).
  • examples/todo has a todos.delete that needs approval, and a test shows todo-mcp's run_program refusing it and naming the writes that did not run.

Behaviour changes

  • Invalid input now fails before ExecuteFunc. Hand-built capabilities with no input Fields are not checked.
  • mcpsource maps integer to integer, records required, and falls back to a tool's title or name when it has no description.
  • agent.Apply runs writes that need approval: applying is the approval.

Verification

  • make test: buf lint, go test ./..., the env check, and the consumer check (new packages build with CGO_ENABLED=0 and link nothing third-party).
  • go test -race on capability/..., codemode/..., agent, mcpserver and examples/todo/....
  • A 10s fuzz run of capability.Validate.
  • make generate after adding the proto option.
  • pnpm run build for the docs (no dead links).
  • go run ./examples/todo and -source proto give the same answer offline.
  • The quickstart's main.go compiled and ran offline as a separate module.
  • Each commit builds and passes tests on its own.
  • go run ./examples/shop and go run ./examples/combined run offline.
  • The taskreport frontend builds and typechecks (pnpm build). Server tests cover holding, approving, rejecting and applying-only-once on both sources. The new buttons were not clicked in a browser, since that needs a live model.

Not in this PR

Tagging v0.1.0, proto typed dispatch, apply_plan over MCP, per-caller identity in mcpsource, and the BAML spike. All are tracked in notes/milestones/2026-11-pluggable-sources.md.

…d answers

Capabilities now come from any source that produces a codemode.Source:
typed Go functions (capability/gosource), protobuf (registry) or MCP tools
(capability/mcpsource), combined with codemode.Combine.

- Validate every capability call against its input shape before
  ExecuteFunc runs; errors name the path and go back to the repair loop.
- gosource.Func derives the schema from Go structs, decodes and encodes,
  and takes access as a required argument.
- agent.RunAs[T] checks and decodes the program's answer into T.
- NeedsApproval holds a write and every later one; agent.PlanStore and
  ApplyPlan apply a plan once, by ID, for its owner.
- TypeSchema gains Required and an integer kind.
app.Source builds the three todo capabilities with gosource; the proto
path stays behind -source proto, and a test asserts both give the same
answer. todo-mcp uses the Go source.
The quickstart builds capabilities from Go structs, returns a typed
answer and approves a write. The protobuf quickstart moves to
docs/content/protobuf.md. Adds ADR 0008 and the pluggable-sources
milestone.
todos.delete is NeedsApproval in both the Go source and todo.proto.
todo-mcp builds its server in newServer, and a test shows run_program
refusing a program that reaches the delete and naming what did not run.
… chat

The 23 capabilities are typed methods on app.App, served by gosource
by default; -source proto keeps the protos, routed to the same methods,
and a test holds both to the same names, descriptions, roles, reads and
approvals.

tasks.delete needs approval. A chat that reaches it returns the held
plan, the page shows Approve and Reject, and POST /api/plans/{id}/approve
or /reject applies or discards it once, for its owner. A delete from the
board is its own approval.
examples/shop is the quickstart as a runnable, tested example: Go-struct
capabilities, a typed answer with RunAs, and a refund approved at the
terminal. examples/combined runs one program over a Go function, the
todo proto service and an in-process MCP server via codemode.Combine.
Both run with no API key (make demo-shop, make demo-combined).
@mukezhz
mukezhz merged commit 858d16b into main Nov 16, 2026
0 of 7 checks passed
@mukezhz
mukezhz deleted the feat/typed-capability-sources branch November 16, 2026 06:09
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant